Skip to content

feat: migrate the site from Honkit to VitePress - #40

Merged
mokevnin merged 2 commits into
mainfrom
feat/vitepress
Nov 21, 2026
Merged

mokevnin merged 2 commits into
mainfrom
feat/vitepress

Conversation

@mokevnin

Copy link
Copy Markdown
Owner

Moves the book from Honkit to VitePress 2 (alpha).

What changes

  • Navigation: the sidebar is generated from each locale's SUMMARY.md, which also renders as a table-of-contents page. That fixes the "table of contents" links on the locale home pages and in "How to read", which 404'd under Honkit.
  • URLs and anchors: the same .html URLs and Honkit-compatible heading ids, so existing links and section anchors keep working.
  • Diagrams: Mermaid is rendered at build time to light and dark SVG images (book/.vitepress/mermaid.mjs). They are <img> tags because Vue strips the <style> inside an inline SVG, so diagram text is no longer selectable.
  • SEO: description, canonical, hreflang and Open Graph tags come from transformHead (book/.vitepress/seo.mjs); the sitemap is VitePress's own, with x-default added.
  • Search: VitePress's built-in local search, with one index per locale.
  • Removed: PDF output, the Honkit plugins and the lunr patch.
  • Tests: unit tests for the sidebar and SEO logic run in mise run check.

Verification

Compared against a Honkit build of main:

  • all 145 page paths are present;
  • heading ids match;
  • page text matches except 10 tables, where Honkit used to drop \<placeholder\> text;
  • meta tags and the sitemap match.

Every diagram type was checked in light and dark mode, plus the mobile layout and the dev server.

🤖 Generated with Claude Code

mokevnin and others added 2 commits November 21, 2026 08:59
Build the book with VitePress 2 (alpha) instead of Honkit:

- sidebar generated from each locale's SUMMARY.md; SUMMARY.md also
  renders as a table-of-contents page, fixing the links that 404'd
- Honkit-compatible heading ids and the same .html URLs
- Mermaid rendered at build time to light/dark SVG images
- SEO head tags via transformHead and the built-in sitemap
- built-in local search per locale; PDF output dropped

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Replace the build-time Playwright renderer, which hung the CI build,
with mokevnin/vitepress-mermaid: diagrams are drawn in the browser and
redrawn on a theme toggle. The book palette and its dark variant are
passed as getters, so each render picks the palette for the current
mode. Playwright and mermaid-isomorphic are no longer dependencies.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@mokevnin
mokevnin merged commit 07bbeae into main Nov 21, 2026
4 checks passed
@mokevnin
mokevnin deleted the feat/vitepress branch November 21, 2026 14:18
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant